*panicparse*
============

Parses panic stack traces, densifies and deduplicates goroutines with similar
stack traces. Helps debugging crashes and deadlocks in heavily parallelized
process.

panicparse helps make sense of Go crash dumps:

![Screencast](parse.gif "Screencast")


Features
--------

   * &gt;50% more compact output than original stack dump yet more readable.
   * Exported symbols are bold, private symbols are darker.
   * Stdlib is green, main is yellow, rest is red.
   * Deduplicates redundant goroutine stacks. Useful for large server crashes.
   * Arguments as pointer IDs instead of raw pointer values.
   * Pushes stdlib-only stacks at the bottom to help focus on important code.
   * Usable as a library!
     [![GoDoc](https://godoc.org/github.com/maruel/panicparse/stack?status.svg)](https://godoc.org/github.com/maruel/panicparse/stack)
     * Warning: please pin the major version (i.e. vendor it via
       [dep](https://github.com/golang/dep)) as breaking changes happen on
       [major version update](https://semver.org/).
   * Parses the source files if available to augment the output.


Usage
-----

### Piping a stack trace from another process

#### TL;DR

   * Ubuntu (bash v4 or zsh): `|&`
   * [Fish](http://fishshell.com/) shell: `^|`


#### Longer version

`pp` streams its stdin to stdout as long as it doesn't detect any panic.
`panic()` and Go's native deadlock detector [print to
stderr](https://golang.org/src/runtime/panic1.go) via the native [`print()`
function](https://golang.org/pkg/builtin/#print).


**Bash v4** or **zsh**: `|&` tells the shell to redirect stderr to stdout,
it's an alias for `2>&1 |` ([bash
v4](https://www.gnu.org/software/bash/manual/bash.html#Pipelines),
[zsh](http://zsh.sourceforge.net/Doc/Release/Shell-Grammar.html#Simple-Commands-_0026-Pipelines)):

    go test -v |&pp


**Fish**: It uses [^ for stderr
redirection](http://fishshell.com/docs/current/tutorial.html#tut_pipes_and_redirections)
so the shortcut is `^|`:

    go test -v ^|pp


### Investigate deadlock

On POSIX, use `Ctrl-\` to send SIGQUIT to your process, `pp` will ignore
the signal and will parse the stack trace.


### Parsing from a file

To dump to a file then parse, pass the file path of a stack trace

    go test 2> stack.txt
    pp stack.txt


Tips
----

### GOTRACEBACK

[`GOTRACEBACK`](https://golang.org/pkg/runtime/) defaults to `single`. 

To get all goroutines trace and not just the crashing one, set the environment variable:

    export GOTRACEBACK=all

Probably worth to put it in your `.bashrc`.

### If you have `/usr/bin/pp` installed

If you try `pp` for the first time and you get:

    Creating tables and indexes...
    Done.

and/or

    /usr/bin/pp5.18: No input files specified

you may be running the _Perl PAR Packager_ instead of panicparse.

You have two choices, either you put `$GOPATH/bin` at the begining of `$PATH` or
use `panicparse` instead of `pp`:

    go test 2> panicparse
